home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / AppleScript / Development Tools / Tools Goodies / AEGizmos 1.4.1 / Documentation / Gizmos Doc.dp (.txt) < prev    next >
Encoding:
Common Ground  |  1995-03-20  |  18.8 KB  |  212 lines  |  [CGDC/CGVM]
  1. Palatino
  2. Apple Events
  3. Gizmos!
  4. Version 1.4
  5. Jens Peter Alfke
  6. 20 March 1995
  7.  Apple Computer, Inc. 1991
  8. New York
  9. Palatino
  10. Apple Event Gizmos
  11. 20 March 1995
  12. Page 
  13. Introduction
  14. OK, What Are They?
  15. AEGizmos
  16. );E consists of four libraries in one. These libraries provide alternate
  17. fFways of building and reading Apple events and Apple event descriptors.
  18. Courier
  19. AEBuild
  20. 6takes a format string 
  21.  a description in a very simple
  22. 7language of an Apple event descriptor 
  23.  and generates a
  24. <real descriptor (which could be a record or list or complete
  25. /Apple event) of arbitrary complexity out of it.
  26. AEPrint
  27. :does the reverse: given an Apple event descriptor, list or
  28. Arecord, it prettyprints it to a string. (The resulting string, if
  29. sent to 
  30. AEBuild
  31. , would reproduce the original 
  32. AEDesc
  33. structure.)
  34. AEStream
  35. 4provides a stream-based protocol that lets you build
  36. :descriptors and events in a linear fashion. The descriptor
  37. 1data stays all in one block and grows in discrete
  38. 5increments, so there will be far fewer Memory Manager
  39. calls.
  40. AESubDescriptors
  41. 8a high-efficiency way to examine and take apart (but not
  42. !modify) Apple Event descriptors (
  43. AEDesc
  44.  structures).
  45. 7Almost everything is done in place, without any copying
  46. 7of data, which avoids most of the overhead of the Apple
  47. 8Event Manager. However, the API is very  similar to that
  48. 2of the Apple Event Manager, which makes it easy to
  49. convert your code.
  50. f5Each library also has its own in-depth documentation.
  51. Palatino
  52. Apple Event Gizmos
  53. Page 
  54. 20 March 1995
  55. s In It For Me?
  56. LFor many common tasks these libraries have clear advantages over the regular
  57. Apple Event API:
  58. Zapf Dingbats
  59. 7They run much faster when building complex descriptors.
  60. They use less heap space.
  61. DThey make your code smaller 
  62. and easier to write
  63.  by requiring fewer
  64. &calls to get things done. (Especially 
  65. Courier
  66. AEBuild
  67. , which can often replace an
  68. r,entire page of code with one function call.)
  69. AEPrint
  70. )*?, which displays an Apple event or descriptor in human-readable
  71. r'form, can be very helpful in debugging.
  72. N*However, they do have their disadvantages:
  73. FThey
  74. re not first-class official Apple Computer products, and have not
  75. Lbeen formally tested. I do some testing on each release, and these libraries
  76. G being used in various projects at Apple (including AppleScript) and by
  77. r7third parties. On the whole they
  78. ve been very reliable.
  79. KThey don
  80. t provide all the functionality and flexibility of the Apple Event
  81. Manager. For instance, 
  82. AEStream
  83.  doesn
  84. t support random access.
  85. HThey
  86. re not as robust when given bad input. For instance, unlike the AEM
  87. ?they don
  88. t check for or disallow duplicate keywords in records.
  89. GThe 68k versions have to be linked into your code. Fortunately, they
  90. very small: even 
  91. AEBuild
  92. )*/, the largest, is under 4k. (On PowerPC they
  93. rIprovided as a shared library. A shared library for 68k (CFM68K) is in the
  94. works.)
  95. N!Just How Stable Are They, Anyway?
  96. OThe Gizmos have been around for several years. In that period they
  97. ve been used
  98. Oin several projects inside and outside Apple. A couple of bugs have been found,
  99. Qwhich I
  100. ve tried to fix as soon as possible. By and large they seem to work fine.
  101. s some more detail:
  102. Palatino
  103. Apple Event Gizmos
  104. 20 March 1995
  105. Page 
  106. fFI do some minimal testing of the code for each release; I verify that 
  107. Courier
  108. AEBuild
  109.  runs
  110. fLreliably on a moderately complex expression, produces exactly the same Apple
  111. Levent structure as does the original C code, and has no memory leakage. This
  112. also gives 
  113. AEStream
  114.  and 
  115. AEPrint
  116.  a good workout.
  117. AEBuild
  118. )*E has also been used in constructing test cases for the Object Support
  119. fOLibrary. These test cases built hideously complex descriptors with no problems.
  120. AEStream
  121. )00 is used in the AppleScript runtime engine. And 
  122. AEBuild
  123.  and 
  124. AEPrint
  125. f5are being used in other Apple code, such as Ed Lai
  126. AESend 
  127. tool, and in third
  128. party software.
  129. MThe sub-descriptors library was tested by creating an experimental version of
  130. AEPrint
  131. )*A that used it instead of the Apple Event Manager; it worked fine.
  132. f0Nonetheless, see the disclaimer presented below.
  133. s always possible for new bugs to be introduced with each release. If you find
  134. Sproblems, first try to revert to an earlier release (check previous developer CDs.)
  135. IAlso make sure to notify me of the problem so I can fix it!  My AppleLink
  136. address is 
  137. Monaco
  138. , and my Internet address is 
  139. Jens_Alfke@powertalk.apple.com
  140. Version History
  141. 3/20/95
  142. )H7Added ability to use AESubDescs on entire Apple Events.
  143. 5Added AECopySubDescData. Fixed several bugs. Released
  144. 5more configurations of the CodeWarrior 68k libraries.
  145. 1.3.4
  146. 6/1/94
  147. )H1Now includes PowerPC libraries. No other changes.
  148. 1.3.3
  149. 10/??/93
  150. )H.Restored floating-point formatting to AEPrint.
  151. 1.3.2
  152. 9/29/93
  153. )H4AESubDescToDesc now works properly when the wantType
  154. 3is typeWildCard. (This used to result in an error.)
  155. AEPrint no longer uses the 
  156. <stdio>
  157.  library. Unfortunately,
  158. 7this means floating point numbers don
  159. t display nicely.
  160. Added 
  161. -model far
  162.  versions of the MPW libraries.
  163. 1.3.1
  164. 7/7/93
  165. )H7Streams consisting of only a single simple (non-nested)
  166. ,descriptor are no longer incorrectly padded.
  167. and that
  168. s as far back as the version history goes.
  169. Palatino
  170. Apple Event Gizmos
  171. Page 
  172. 20 March 1995
  173. Disclaimer
  174. OFTWARE 
  175. AINSTAKINGLY 
  176. ESTED 
  177.     UTHLESSLY
  178.     FFICIENT 
  179. UALITY 
  180. NGINEERS
  181. EITHER 
  182. PPLE 
  183. OMPUTER
  184. NCORPORATED
  185. OR THE 
  186.     UTHOR OF 
  187. OFTWARE 
  188. EGALLY 
  189. INDING 
  190. LAIM 
  191. OFTWARE 
  192. SE AT 
  193. AVE A 
  194. >+.8,
  195. =3-A@2
  196. !("9U
  197. p 0p`P
  198. =?7,<.
  199. xP(H`X 
  200.     temp.0001
  201. Jens Alfke
  202. Apple Computer
  203. Microsoft Word
  204. New York
  205. Monaco
  206. Zapf Dingbats
  207. Palatino
  208. Courier
  209. bPREC
  210. nPRVS
  211. zCAPN
  212.